<?xml version="1.0" encoding="ascii"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
          "DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
  <title>netcdftime.netcdftime.utime</title>
  <link rel="stylesheet" href="epydoc.css" type="text/css" />
  <script type="text/javascript" src="epydoc.js"></script>
</head>

<body bgcolor="white" text="black" link="blue" vlink="#204080"
      alink="#204080">
<!-- ==================== NAVIGATION BAR ==================== -->
<table class="navbar" border="0" width="100%" cellpadding="0"
       bgcolor="#a0c0ff" cellspacing="0">
  <tr valign="middle">

  <!-- Tree link -->
      <th>&nbsp;&nbsp;&nbsp;<a
        href="module-tree.html">Trees</a>&nbsp;&nbsp;&nbsp;</th>

  <!-- Index link -->
      <th>&nbsp;&nbsp;&nbsp;<a
        href="identifier-index.html">Indices</a>&nbsp;&nbsp;&nbsp;</th>

  <!-- Help link -->
      <th>&nbsp;&nbsp;&nbsp;<a
        href="help.html">Help</a>&nbsp;&nbsp;&nbsp;</th>

      <th class="navbar" width="100%"></th>
  </tr>
</table>
<table width="100%" cellpadding="0" cellspacing="0">
  <tr valign="top">
    <td width="100%">
      <span class="breadcrumbs">
        Package&nbsp;netcdftime ::
        <a href="netcdftime.netcdftime-module.html">Module&nbsp;netcdftime</a> ::
        Class&nbsp;utime
      </span>
    </td>
    <td>
      <table cellpadding="0" cellspacing="0">
        <!-- hide/show private -->
      </table>
    </td>
  </tr>
</table>
<!-- ==================== CLASS DESCRIPTION ==================== -->
<h1 class="epydoc">Class utime</h1><p class="nomargin-top"><span class="codelink"><a href="netcdftime.netcdftime-pysrc.html#utime">source&nbsp;code</a></span></p>
<p>Performs conversions of netCDF time coordinate data to/from datetime 
  objects.</p>
  <p>To initialize: <code>t = 
  utime(unit_string,calendar='standard')</code></p>
  <p>where</p>
  <p><b><code>unit_string</code></b> is a string of the form 
  <code>'time-units since &lt;time-origin&gt;'</code> defining the time 
  units.</p>
  <p>Valid time-units are days, hours, minutes and seconds (the singular 
  forms are also accepted). An example unit_string would be <code>'hours 
  since 0001-01-01 00:00:00'</code>.</p>
  <p>The <b><code>calendar</code></b> keyword describes the calendar used 
  in the time calculations. All the values currently defined in the <a 
  href="http://cf-pcmdi.llnl.gov/documents/cf-conventions/1.1/cf-conventions.html#time-coordinate"
  target="_top">CF metadata convention</a> are accepted. The default is 
  <code>'standard'</code>, which corresponds to the mixed Gregorian/Julian 
  calendar used by the <code>udunits library</code>. Valid calendars 
  are:</p>
  <p><code>'gregorian'</code> or <code>'standard'</code> (default):</p>
  <p>Mixed Gregorian/Julian calendar as defined by udunits.</p>
  <p><code>'proleptic_gregorian'</code>:</p>
  <p>A Gregorian calendar extended to dates before 1582-10-15. That is, a 
  year is a leap year if either (i) it is divisible by 4 but not by 100 or 
  (ii) it is divisible by 400.</p>
  <p><code>'noleap'</code> or <code>'365_day'</code>:</p>
  <p>Gregorian calendar without leap years, i.e., all years are 365 days 
  long. all_leap or 366_day Gregorian calendar with every year being a leap
  year, i.e., all years are 366 days long.</p>
  <p><code>'360_day'</code>:</p>
  <p>All years are 360 days divided into 30 day months.</p>
  <p><code>'julian'</code>:</p>
  <p>Proleptic Julian calendar, extended to dates after 1582-10-5. A year 
  is a leap year if it is divisible by 4.</p>
  <p>The <code><a href="netcdftime.netcdftime.utime-class.html#num2date" 
  class="link">num2date</a></code> and <code><a 
  href="netcdftime.netcdftime.utime-class.html#date2num" 
  class="link">date2num</a></code> class methods can used to convert 
  datetime instances to/from the specified time units using the specified 
  calendar.</p>
  <p>The datetime instances returned by <code>num2date</code> are 'real' 
  python datetime objects if the date falls in the Gregorian calendar (i.e.
  <code>calendar='proleptic_gregorian', 'standard'</code> or 
  <code>'gregorian'</code> and the date is after 1582-10-15). Otherwise, 
  they are 'phony' datetime objects which are actually instances of 
  <code><a href="netcdftime.netcdftime.datetime-class.html" 
  class="link">netcdftime.datetime</a></code>.  This is because the python 
  datetime module cannot handle the weird dates in some calendars (such as 
  <code>'360_day'</code> and <code>'all_leap'</code>) which don't exist in 
  any real world calendar.</p>
  <p>Example usage:</p>
<pre class="py-doctest">
<span class="py-prompt">&gt;&gt;&gt; </span><span class="py-keyword">from</span> netcdftime <span class="py-keyword">import</span> utime
<span class="py-prompt">&gt;&gt;&gt; </span><span class="py-keyword">from</span> datetime <span class="py-keyword">import</span>  datetime
<span class="py-prompt">&gt;&gt;&gt; </span>cdftime = utime(<span class="py-string">'hours since 0001-01-01 00:00:00'</span>)
<span class="py-prompt">&gt;&gt;&gt; </span>date = datetime.now()
<span class="py-prompt">&gt;&gt;&gt; </span><span class="py-keyword">print</span> date
<span class="py-output">2006-03-17 16:04:02.561678</span>
<span class="py-output"></span><span class="py-prompt">&gt;&gt;&gt;</span>
<span class="py-prompt">&gt;&gt;&gt; </span>t = cdftime.date2num(date)
<span class="py-prompt">&gt;&gt;&gt; </span><span class="py-keyword">print</span> t
<span class="py-output">17577328.0672</span>
<span class="py-output"></span><span class="py-prompt">&gt;&gt;&gt;</span>
<span class="py-prompt">&gt;&gt;&gt; </span>date = cdftime.num2date(t)
<span class="py-prompt">&gt;&gt;&gt; </span><span class="py-keyword">print</span> date
<span class="py-output">2006-03-17 16:04:02</span>
<span class="py-output"></span><span class="py-prompt">&gt;&gt;&gt;</span></pre>
  <p>The resolution of the transformation operation is 1 second.</p>
  <p>Warning:  Dates between 1582-10-5 and 1582-10-15 do not exist in the 
  <code>'standard'</code> or <code>'gregorian'</code> calendars.  An 
  exception will be raised if you pass a 'datetime-like' object in that 
  range to the <code><a 
  href="netcdftime.netcdftime.utime-class.html#date2num" 
  class="link">date2num</a></code> class method.</p>
  <p>Words of Wisdom from the British MetOffice concerning reference 
  dates:</p>
  <p>&quot;udunits implements the mixed Gregorian/Julian calendar system, 
  as followed in England, in which dates prior to 1582-10-15 are assumed to
  use the Julian calendar. Other software cannot be relied upon to handle 
  the change of calendar in the same way, so for robustness it is 
  recommended that the reference date be later than 1582. If earlier dates 
  must be used, it should be noted that udunits treats 0 AD as identical to
  1 AD.&quot;</p>

<!-- ==================== INSTANCE METHODS ==================== -->
<a name="section-InstanceMethods"></a>
<table class="summary" border="1" cellpadding="3"
       cellspacing="0" width="100%" bgcolor="white">
<tr bgcolor="#70b0f0" class="table-header">
  <td align="left" colspan="2" class="table-header">
    <span class="table-header">Instance Methods</span></td>
</tr>
<tr>
    <td width="15%" align="right" valign="top" class="summary">
      <span class="summary-type">&nbsp;</span>
    </td><td class="summary">
      <table width="100%" cellpadding="0" cellspacing="0" border="0">
        <tr>
          <td><span class="summary-sig"><a href="netcdftime.netcdftime.utime-class.html#__init__" class="summary-sig-name">__init__</a>(<span class="summary-sig-arg">self</span>,
        <span class="summary-sig-arg">unit_string</span>,
        <span class="summary-sig-arg">calendar</span>=<span class="summary-sig-default"><code class="variable-quote">'</code><code class="variable-string">standard</code><code class="variable-quote">'</code></span>)</span><br />
      Returns:
      A class instance which may be used for converting times from netCDF 
      units to datetime objects.</td>
          <td align="right" valign="top">
            <span class="codelink"><a href="netcdftime.netcdftime-pysrc.html#utime.__init__">source&nbsp;code</a></span>
            
          </td>
        </tr>
      </table>
      
    </td>
  </tr>
<tr>
    <td width="15%" align="right" valign="top" class="summary">
      <span class="summary-type">&nbsp;</span>
    </td><td class="summary">
      <table width="100%" cellpadding="0" cellspacing="0" border="0">
        <tr>
          <td><span class="summary-sig"><a href="netcdftime.netcdftime.utime-class.html#date2num" class="summary-sig-name">date2num</a>(<span class="summary-sig-arg">self</span>,
        <span class="summary-sig-arg">date</span>)</span><br />
      Returns <code>time_value</code> in units described by <a 
      href="netcdftime.netcdftime.utime-class.html#unit_string" 
      class="link">unit_string</a>, using the specified <a 
      href="netcdftime.netcdftime.utime-class.html#calendar" 
      class="link">calendar</a>, given a 'datetime-like' object.</td>
          <td align="right" valign="top">
            <span class="codelink"><a href="netcdftime.netcdftime-pysrc.html#utime.date2num">source&nbsp;code</a></span>
            
          </td>
        </tr>
      </table>
      
    </td>
  </tr>
<tr>
    <td width="15%" align="right" valign="top" class="summary">
      <span class="summary-type">&nbsp;</span>
    </td><td class="summary">
      <table width="100%" cellpadding="0" cellspacing="0" border="0">
        <tr>
          <td><span class="summary-sig"><a href="netcdftime.netcdftime.utime-class.html#num2date" class="summary-sig-name">num2date</a>(<span class="summary-sig-arg">self</span>,
        <span class="summary-sig-arg">time_value</span>)</span><br />
      Return a 'datetime-like' object given a <code>time_value</code> in 
      units described by <a 
      href="netcdftime.netcdftime.utime-class.html#unit_string" 
      class="link">unit_string</a>, using <a 
      href="netcdftime.netcdftime.utime-class.html#calendar" 
      class="link">calendar</a>.</td>
          <td align="right" valign="top">
            <span class="codelink"><a href="netcdftime.netcdftime-pysrc.html#utime.num2date">source&nbsp;code</a></span>
            
          </td>
        </tr>
      </table>
      
    </td>
  </tr>
</table>
<!-- ==================== INSTANCE VARIABLES ==================== -->
<a name="section-InstanceVariables"></a>
<table class="summary" border="1" cellpadding="3"
       cellspacing="0" width="100%" bgcolor="white">
<tr bgcolor="#70b0f0" class="table-header">
  <td align="left" colspan="2" class="table-header">
    <span class="table-header">Instance Variables</span></td>
</tr>
<tr>
    <td width="15%" align="right" valign="top" class="summary">
      <span class="summary-type">&nbsp;</span>
    </td><td class="summary">
        <a name="calendar"></a><span class="summary-name">calendar</span><br />
      the calendar used (as specified by the <code>calendar</code> 
      keyword).
    </td>
  </tr>
<tr>
    <td width="15%" align="right" valign="top" class="summary">
      <span class="summary-type">&nbsp;</span>
    </td><td class="summary">
        <a name="origin"></a><span class="summary-name">origin</span><br />
      datetime instance defining the origin of the netCDF time variable.
    </td>
  </tr>
<tr>
    <td width="15%" align="right" valign="top" class="summary">
      <span class="summary-type">&nbsp;</span>
    </td><td class="summary">
        <a name="unit_string"></a><span class="summary-name">unit_string</span><br />
      a string defining the the netCDF time variable.
    </td>
  </tr>
<tr>
    <td width="15%" align="right" valign="top" class="summary">
      <span class="summary-type">&nbsp;</span>
    </td><td class="summary">
        <a href="netcdftime.netcdftime.utime-class.html#units" class="summary-name">units</a><br />
      the units part of <code>unit_string</code> (i.e.
    </td>
  </tr>
</table>
<!-- ==================== METHOD DETAILS ==================== -->
<a name="section-MethodDetails"></a>
<table class="details" border="1" cellpadding="3"
       cellspacing="0" width="100%" bgcolor="white">
<tr bgcolor="#70b0f0" class="table-header">
  <td align="left" colspan="2" class="table-header">
    <span class="table-header">Method Details</span></td>
</tr>
</table>
<a name="__init__"></a>
<div>
<table class="details" border="1" cellpadding="3"
       cellspacing="0" width="100%" bgcolor="white">
<tr><td>
  <table width="100%" cellpadding="0" cellspacing="0" border="0">
  <tr valign="top"><td>
  <h3 class="epydoc"><span class="sig"><span class="sig-name">__init__</span>(<span class="sig-arg">self</span>,
        <span class="sig-arg">unit_string</span>,
        <span class="sig-arg">calendar</span>=<span class="sig-default"><code class="variable-quote">'</code><code class="variable-string">standard</code><code class="variable-quote">'</code></span>)</span>
    <br /><em class="fname">(Constructor)</em>
  </h3>
  </td><td align="right" valign="top"
    ><span class="codelink"><a href="netcdftime.netcdftime-pysrc.html#utime.__init__">source&nbsp;code</a></span>&nbsp;
    </td>
  </tr></table>
  
  
  <dl class="fields">
    <dt>Parameters:</dt>
    <dd><ul class="nomargin-top">
        <li><strong class="pname"><code>unit_string</code></strong> - a string of the form <code>'time-units since 
          &lt;time-origin&gt;'</code> defining the time units.
          <p>Valid time-units are days, hours, minutes and seconds (the 
          singular forms are also accepted). An example unit_string would 
          be <code>'hours since 0001-01-01 00:00:00'</code>.</p></li>
        <li><strong class="pname"><code>calendar</code></strong> - describes the calendar used in the time calculations. All the 
          values currently defined in the <a 
          href="http://cf-pcmdi.llnl.gov/documents/cf-conventions/1.1/cf-conventions.html#time-coordinate"
          target="_top">CF metadata convention</a> are accepted. The 
          default is <code>'standard'</code>, which corresponds to the 
          mixed Gregorian/Julian calendar used by the <code>udunits 
          library</code>. Valid calendars are:
          <ul>
            <li>
              <code>'gregorian'</code> or <code>'standard'</code> 
              (default): Mixed Gregorian/Julian calendar as defined by 
              udunits.
            </li>
            <li>
              <code>'proleptic_gregorian'</code>: A Gregorian calendar 
              extended to dates before 1582-10-15. That is, a year is a 
              leap year if either (i) it is divisible by 4 but not by 100 
              or (ii) it is divisible by 400.
            </li>
            <li>
              <code>'noleap'</code> or <code>'365_day'</code>: Gregorian 
              calendar without leap years, i.e., all years are 365 days 
              long.
            </li>
            <li>
              <code>'all_leap'</code> or <code>'366_day'</code>: Gregorian 
              calendar with every year being a leap year, i.e., all years 
              are 366 days long. -<code>'360_day'</code>: All years are 360
              days divided into 30 day months. -<code>'julian'</code>: 
              Proleptic Julian calendar, extended to dates after 1582-10-5.
              A year is a leap year if it is divisible by 4.
            </li>
          </ul></li>
    </ul></dd>
    <dt>Returns:</dt>
        <dd>A class instance which may be used for converting times from 
          netCDF units to datetime objects.</dd>
  </dl>
</td></tr></table>
</div>
<a name="date2num"></a>
<div>
<table class="details" border="1" cellpadding="3"
       cellspacing="0" width="100%" bgcolor="white">
<tr><td>
  <table width="100%" cellpadding="0" cellspacing="0" border="0">
  <tr valign="top"><td>
  <h3 class="epydoc"><span class="sig"><span class="sig-name">date2num</span>(<span class="sig-arg">self</span>,
        <span class="sig-arg">date</span>)</span>
  </h3>
  </td><td align="right" valign="top"
    ><span class="codelink"><a href="netcdftime.netcdftime-pysrc.html#utime.date2num">source&nbsp;code</a></span>&nbsp;
    </td>
  </tr></table>
  
  <p>Returns <code>time_value</code> in units described by <a 
  href="netcdftime.netcdftime.utime-class.html#unit_string" 
  class="link">unit_string</a>, using the specified <a 
  href="netcdftime.netcdftime.utime-class.html#calendar" 
  class="link">calendar</a>, given a 'datetime-like' object.</p>
  <p>The datetime object must represent UTC with no time-zone offset. If 
  there is a time-zone offset implied by <a 
  href="netcdftime.netcdftime.utime-class.html#unit_string" 
  class="link">unit_string</a>, it will be applied to the returned numeric 
  values.</p>
  <p>Resolution is 1 second.</p>
  <p>If <code>calendar = 'standard'</code> or <code>'gregorian'</code> 
  (indicating that the mixed Julian/Gregorian calendar is to be used), an 
  exception will be raised if the 'datetime-like' object describes a date 
  between 1582-10-5 and 1582-10-15.</p>
  <p>Works for scalars, sequences and numpy arrays. Returns a scalar if 
  input is a scalar, else returns a numpy array.</p>
  <dl class="fields">
  </dl>
</td></tr></table>
</div>
<a name="num2date"></a>
<div>
<table class="details" border="1" cellpadding="3"
       cellspacing="0" width="100%" bgcolor="white">
<tr><td>
  <table width="100%" cellpadding="0" cellspacing="0" border="0">
  <tr valign="top"><td>
  <h3 class="epydoc"><span class="sig"><span class="sig-name">num2date</span>(<span class="sig-arg">self</span>,
        <span class="sig-arg">time_value</span>)</span>
  </h3>
  </td><td align="right" valign="top"
    ><span class="codelink"><a href="netcdftime.netcdftime-pysrc.html#utime.num2date">source&nbsp;code</a></span>&nbsp;
    </td>
  </tr></table>
  
  <p>Return a 'datetime-like' object given a <code>time_value</code> in 
  units described by <a 
  href="netcdftime.netcdftime.utime-class.html#unit_string" 
  class="link">unit_string</a>, using <a 
  href="netcdftime.netcdftime.utime-class.html#calendar" 
  class="link">calendar</a>.</p>
  <p>dates are in UTC with no offset, even if <a 
  href="netcdftime.netcdftime.utime-class.html#unit_string" 
  class="link">unit_string</a> contains a time zone offset from UTC.</p>
  <p>Resolution is 1 second.</p>
  <p>Works for scalars, sequences and numpy arrays. Returns a scalar if 
  input is a scalar, else returns a numpy array.</p>
  <p>The datetime instances returned by <code>num2date</code> are 'real' 
  python datetime objects if the date falls in the Gregorian calendar (i.e.
  <code>calendar='proleptic_gregorian'</code>, or <code>calendar = 
  'standard'/'gregorian'</code> and the date is after 1582-10-15). 
  Otherwise, they are 'phony' datetime objects which are actually instances
  of netcdftime.datetime.  This is because the python datetime module 
  cannot handle the weird dates in some calendars (such as 
  <code>'360_day'</code> and <code>'all_leap'</code>) which do not exist in
  any real world calendar.</p>
  <dl class="fields">
  </dl>
</td></tr></table>
</div>
<br />
<!-- ==================== INSTANCE VARIABLE DETAILS ==================== -->
<a name="section-InstanceVariableDetails"></a>
<table class="details" border="1" cellpadding="3"
       cellspacing="0" width="100%" bgcolor="white">
<tr bgcolor="#70b0f0" class="table-header">
  <td align="left" colspan="2" class="table-header">
    <span class="table-header">Instance Variable Details</span></td>
</tr>
</table>
<a name="units"></a>
<div>
<table class="details" border="1" cellpadding="3"
       cellspacing="0" width="100%" bgcolor="white">
<tr><td>
  <h3 class="epydoc">units</h3>
  the units part of <code>unit_string</code> (i.e. 'days', 'hours', 
  'seconds').
  <dl class="fields">
  </dl>
</td></tr></table>
</div>
<br />
<!-- ==================== NAVIGATION BAR ==================== -->
<table class="navbar" border="0" width="100%" cellpadding="0"
       bgcolor="#a0c0ff" cellspacing="0">
  <tr valign="middle">

  <!-- Tree link -->
      <th>&nbsp;&nbsp;&nbsp;<a
        href="module-tree.html">Trees</a>&nbsp;&nbsp;&nbsp;</th>

  <!-- Index link -->
      <th>&nbsp;&nbsp;&nbsp;<a
        href="identifier-index.html">Indices</a>&nbsp;&nbsp;&nbsp;</th>

  <!-- Help link -->
      <th>&nbsp;&nbsp;&nbsp;<a
        href="help.html">Help</a>&nbsp;&nbsp;&nbsp;</th>

      <th class="navbar" width="100%"></th>
  </tr>
</table>
<table border="0" cellpadding="0" cellspacing="0" width="100%%">
  <tr>
    <td align="left" class="footer">
    Generated by Epydoc 3.0.1 on Thu Jul  8 10:58:35 2010
    </td>
    <td align="right" class="footer">
      <a target="mainFrame" href="http://epydoc.sourceforge.net"
        >http://epydoc.sourceforge.net</a>
    </td>
  </tr>
</table>

<script type="text/javascript">
  <!--
  // Private objects are initially displayed (because if
  // javascript is turned off then we want them to be
  // visible); but by default, we want to hide them.  So hide
  // them unless we have a cookie that says to show them.
  checkCookie();
  // -->
</script>
</body>
</html>
